Design System Foundation

**Referenced Files in This Document** - [01-variables-reset.css](file://src/assets/css/modules/01-variables-reset.css) - [02-global-utilities.css](file://src/assets/css/modules/02-global-utilities.css) - [03-custom-cursor.css](file://src/assets/css/modules/03-custom-cursor.css) - [25-responsive-tablet-max-width-1024px.css](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css) - [26-responsive-mobile-max-width-900px.css](file://src/assets/css/modules/26-responsive-mobile-max-width-900px.css) - [27-responsive-small-mobile-max-width-600px.css](file://src/assets/css/modules/27-responsive-small-mobile-max-width-600px.css) - [28-responsive-extra-small-max-width-480px.css](file://src/assets/css/modules/28-responsive-extra-small-max-width-480px.css) - [38-material-design-3-theme-toggle.css](file://src/assets/css/modules/38-material-design-3-theme-toggle.css) - [39-material-design-3-theme-toggle-complete.css](file://src/assets/css/modules/39-material-design-3-theme-toggle-complete.css) - [main.css](file://src/assets/css/main.css) - [material-design-3-main-theme-toggle.js](file://src/assets/js/modules/material-design-3-main-theme-toggle.js) - [iaa-alliance-theme-toggle.js](file://src/assets/js/modules/iaa-alliance-theme-toggle.js) - [theme-toggling.js](file://src/assets/js/modules/theme-toggling.js) - [main.js](file://src/assets/js/main.js)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction

This document describes the design system foundation of the project, focusing on the CSS variables system, reset and normalization styles, global utility classes, Material Design 3 theming, and the theme switching mechanism. It explains how design tokens (colors, typography, spacing, elevation) are defined and consumed, how global utilities provide consistent baseline styling, and how theme toggles integrate with the DOM and persistence to deliver a cohesive light/dark experience across components.

Project Structure

The design system foundation is organized as modular CSS and JavaScript assets imported into a single main stylesheet and script bundle. CSS modules define variables, resets, utilities, responsive breakpoints, and MD3 theme toggles. JavaScript modules initialize theme toggles and observe theme changes in content sections.

graph TB
subgraph "CSS Modules"
V["01-variables-reset.css"]
U["02-global-utilities.css"]
C["03-custom-cursor.css"]
R1["25-responsive-tablet-max-width-1024px.css"]
R2["26-responsive-mobile-max-width-900px.css"]
R3["27-responsive-small-mobile-max-width-600px.css"]
R4["28-responsive-extra-small-max-width-480px.css"]
T1["38-material-design-3-theme-toggle.css"]
T2["39-material-design-3-theme-toggle-complete.css"]
end
M["main.css"]
subgraph "JS Modules"
J1["material-design-3-main-theme-toggle.js"]
J2["iaa-alliance-theme-toggle.js"]
J3["theme-toggling.js"]
JM["main.js"]
end
V --> M
U --> M
C --> M
R1 --> M
R2 --> M
R3 --> M
R4 --> M
T1 --> M
T2 --> M
J1 --> JM
J2 --> JM
J3 --> JM
JM --> M

Diagram sources

  • [main.css:1-47](file://src/assets/css/main.css#L1-L47)
  • [main.js:1-37](file://src/assets/js/main.js#L1-L37)

Section sources

  • [main.css:1-47](file://src/assets/css/main.css#L1-L47)
  • [main.js:1-37](file://src/assets/js/main.js#L1-L37)

Core Components

  • CSS Variables and Reset: Defines brand colors, glassmorphism tokens, shadows, typography scale, layout constraints, and transitions. Normalizes margins/padding and establishes box sizing.
  • Global Utilities: Sets base font size, smooth scrolling, accessibility focus rings, image responsiveness, and noise overlay.
  • Material Design 3 Theming: Establishes MD3 color roles and elevation tokens, and defines theme-specific overrides for light/dark modes.
  • Theme Toggle JS: Initializes persistent theme toggles for the main site and IAA page, and observes theme changes in content sections.
  • Responsive Breakpoints: Media queries for tablet, mobile, small mobile, and extra-small screens adjust layout and typography.

Practical usage examples:

  • Variable usage: Apply a brand color via a custom property or use a shadow/elevation token for depth.
  • Inheritance: Custom properties cascade from :root to components, enabling consistent theming.
  • Theme switching: Toggling body classes updates all dependent selectors and persists preferences in local storage.

Section sources

  • [01-variables-reset.css:11-64](file://src/assets/css/modules/01-variables-reset.css#L11-L64)
  • [02-global-utilities.css:5-64](file://src/assets/css/modules/02-global-utilities.css#L5-L64)
  • [38-material-design-3-theme-toggle.css:6-14](file://src/assets/css/modules/38-material-design-3-theme-toggle.css#L6-L14)
  • [39-material-design-3-theme-toggle-complete.css:20-23](file://src/assets/css/modules/39-material-design-3-theme-toggle-complete.css#L20-L23)
  • [material-design-3-main-theme-toggle.js:3-35](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L3-L35)
  • [iaa-alliance-theme-toggle.js:3-35](file://src/assets/js/modules/iaa-alliance-theme-toggle.js#L3-L35)
  • [theme-toggling.js:3-21](file://src/assets/js/modules/theme-toggling.js#L3-L21)

Architecture Overview

The design system integrates CSS custom properties with JavaScript-driven theme toggles and intersection observers. CSS modules provide tokens and utilities; JS initializes toggles and updates body classes, which drive theme-dependent selectors in CSS.

sequenceDiagram
participant User as "User"
participant DOM as "DOM"
participant JS as "Theme Toggle JS"
participant CSS as "MD3 Theme CSS"
User->>DOM : Click theme toggle
DOM->>JS : Event listener fires
JS->>JS : Determine new theme
JS->>DOM : Add/remove theme-light/theme-dark classes
JS->>DOM : Persist preference in localStorage
DOM->>CSS : Apply theme-specific selectors
CSS-->>User : Rendered UI updates (colors, shadows, borders)

Diagram sources

  • [material-design-3-main-theme-toggle.js:17-27](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L17-L27)
  • [38-material-design-3-theme-toggle.css:17-33](file://src/assets/css/modules/38-material-design-3-theme-toggle.css#L17-L33)
  • [39-material-design-3-theme-toggle-complete.css:20-23](file://src/assets/css/modules/39-material-design-3-theme-toggle-complete.css#L20-L23)

Detailed Component Analysis

CSS Variables System

  • Color palettes:
    • Brand HSL-based palette (navy, sky blue, red, gold) with light/dark variants.
    • Background tokens for light/dark themes.
  • Elevation and depth:
    • MD3-like elevation tokens and glassmorphism tokens for modern UI effects.
  • Typography:
    • Font families and a scale using relative units and clamp for fluid headings.
  • Spacing and layout:
    • Max widths, border radii, and transition timing functions.
  • Motion:
    • Predefined easing curves for fast, smooth, and bounce transitions.

Usage patterns:

  • Reference brand colors via custom properties in components.
  • Combine elevation tokens with box-shadow for depth.
  • Use typography scale tokens for headings and body text.

Section sources

  • [01-variables-reset.css:11-64](file://src/assets/css/modules/01-variables-reset.css#L11-L64)

Reset and Normalization Styles

  • Universal reset for margins and paddings with border-box sizing.
  • HTML/body width and overflow controls.
  • Smooth scrolling and font smoothing for readability.
  • Accessible focus ring for keyboard navigation.
  • Noise overlay for subtle texture.

Integration:

  • These styles normalize browser defaults and provide a consistent baseline for all components.

Section sources

  • [01-variables-reset.css:5-9](file://src/assets/css/modules/01-variables-reset.css#L5-L9)
  • [02-global-utilities.css:5-27](file://src/assets/css/modules/02-global-utilities.css#L5-L27)
  • [02-global-utilities.css:47-51](file://src/assets/css/modules/02-global-utilities.css#L47-L51)
  • [02-global-utilities.css:53-61](file://src/assets/css/modules/02-global-utilities.css#L53-L61)

Global Utility Classes

  • Base font size, scroll behavior, and text-size-adjust.
  • Body-level color/background and line-height with transitions.
  • Headings with hyphenation and max-width constraints.
  • Image responsiveness and anchor transitions.
  • Focus-visible ring with gold accent for accessibility.
  • Noise overlay for visual texture.

These utilities ensure consistent typography, interaction feedback, and accessibility across pages.

Section sources

  • [02-global-utilities.css:5-17](file://src/assets/css/modules/02-global-utilities.css#L5-L17)
  • [02-global-utilities.css:19-44](file://src/assets/css/modules/02-global-utilities.css#L19-L44)
  • [02-global-utilities.css:46-51](file://src/assets/css/modules/02-global-utilities.css#L46-L51)
  • [02-global-utilities.css:53-61](file://src/assets/css/modules/02-global-utilities.css#L53-L61)

Material Design 3 Implementation

  • MD3 color roles:
    • Primary, surface, on-surface, and outline tokens mapped to brand variables.
  • Elevation tokens:
    • md-elevation-1/2/3 used for shadows and interactive states.
  • Theme states:
    • body.theme-light and body.theme-dark define primary/background/text tokens and component-level overrides.
  • Component tokens:
    • Track/handle/halo states for the theme toggle switch reflect elevation and color roles.

Practical examples:

  • Use --md-sys-color-primary for prominent actions.
  • Apply --md-elevation-2 to cards and modals for depth.
  • Switch body classes to activate theme-specific component styles.

Section sources

  • [38-material-design-3-theme-toggle.css:6-14](file://src/assets/css/modules/38-material-design-3-theme-toggle.css#L6-L14)
  • [38-material-design-3-theme-toggle.css:17-33](file://src/assets/css/modules/38-material-design-3-theme-toggle.css#L17-L33)
  • [39-material-design-3-theme-toggle-complete.css:20-23](file://src/assets/css/modules/39-material-design-3-theme-toggle-complete.css#L20-L23)

Theme Switching Mechanisms

  • Main theme toggle:
    • Reads saved preference from localStorage, applies body classes, and toggles aria-checked.
    • Supports click and keyboard activation.
  • IAA theme toggle:
    • Standalone implementation with its own storage key and body class toggling.
  • Content theme observer:
    • Uses IntersectionObserver to toggle on-light-bg/on-dark-bg based on the data-theme of intersecting sections.

Initialization:

  • All JS modules are imported and initialized in main.js during DOMContentLoaded.
sequenceDiagram
participant Init as "main.js"
participant MainToggle as "material-design-3-main-theme-toggle.js"
participant IAA as "iaa-alliance-theme-toggle.js"
participant Observer as "theme-toggling.js"
participant DOM as "DOM"
Init->>MainToggle : initThemeToggle()
Init->>IAA : initIAAThemeToggle()
Init->>Observer : initThemeToggling()
MainToggle->>DOM : Set body classes and aria-checked
IAA->>DOM : Set body classes and aria-checked
Observer->>DOM : Toggle on-light-bg/on-dark-bg based on intersection

Diagram sources

  • [main.js:15-26](file://src/assets/js/main.js#L15-L26)
  • [material-design-3-main-theme-toggle.js:3-35](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L3-L35)
  • [iaa-alliance-theme-toggle.js:3-35](file://src/assets/js/modules/iaa-alliance-theme-toggle.js#L3-L35)
  • [theme-toggling.js:9-18](file://src/assets/js/modules/theme-toggling.js#L9-L18)

Section sources

  • [material-design-3-main-theme-toggle.js:3-35](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L3-L35)
  • [iaa-alliance-theme-toggle.js:3-35](file://src/assets/js/modules/iaa-alliance-theme-toggle.js#L3-L35)
  • [theme-toggling.js:3-21](file://src/assets/js/modules/theme-toggling.js#L3-L21)
  • [main.js:15-26](file://src/assets/js/main.js#L15-L26)

Responsive Breakpoints and Grid Adjustments

  • Tablet (max-width: 1024px):
    • Mobile menu with animated clip-path, adjusted section padding, and carousel/card sizes.
  • Mobile (max-width: 900px):
    • Reduced base font size, stacked hero content, and responsive grids for services, teams, and news.
  • Small mobile (max-width: 600px):
    • Single-column grids for process and case studies, stacked service detail rows.
  • Extra-small (max-width: 480px):
    • Further adjustments for team grids and hero CTA circle.

These breakpoints ensure consistent layouts across devices while preserving component semantics.

Section sources

  • [25-responsive-tablet-max-width-1024px.css:6-330](file://src/assets/css/modules/25-responsive-tablet-max-width-1024px.css#L6-L330)
  • [26-responsive-mobile-max-width-900px.css:6-357](file://src/assets/css/modules/26-responsive-mobile-max-width-900px.css#L6-L357)
  • [27-responsive-small-mobile-max-width-600px.css:5-36](file://src/assets/css/modules/27-responsive-small-mobile-max-width-600px.css#L5-L36)
  • [28-responsive-extra-small-max-width-480px.css:5-13](file://src/assets/css/modules/28-responsive-extra-small-max-width-480px.css#L5-L13)

Cursor and Visual Effects

  • Custom cursor module:
    • Implements a dual-layer cursor with hover scaling and glow effects.
    • Adapts colors based on background theme via on-light-bg/on-dark-bg classes.
  • Accessibility and motion:
    • Reduces motion for reduced-motion users via separate module imports.

Section sources

  • [03-custom-cursor.css:5-43](file://src/assets/css/modules/03-custom-cursor.css#L5-L43)
  • [main.js:1-14](file://src/assets/js/main.js#L1-L14)

Dependency Analysis

The design system composes CSS modules into a single stylesheet and initializes JS modules on page load. Theme toggles depend on localStorage and DOM classes to propagate theme changes. IntersectionObserver enables dynamic theme awareness in content sections.

graph LR
CSS_Main["main.css"] --> Vars["01-variables-reset.css"]
CSS_Main --> Utils["02-global-utilities.css"]
CSS_Main --> Cursor["03-custom-cursor.css"]
CSS_Main --> MD3_Toggle["38-material-design-3-theme-toggle.css"]
CSS_Main --> MD3_Complete["39-material-design-3-theme-toggle-complete.css"]
CSS_Main --> Resp1["25-responsive-tablet-max-width-1024px.css"]
CSS_Main --> Resp2["26-responsive-mobile-max-width-900px.css"]
CSS_Main --> Resp3["27-responsive-small-mobile-max-width-600px.css"]
CSS_Main --> Resp4["28-responsive-extra-small-max-width-480px.css"]
JS_Main["main.js"] --> ToggleMain["material-design-3-main-theme-toggle.js"]
JS_Main --> ToggleIAA["iaa-alliance-theme-toggle.js"]
JS_Main --> Obs["theme-toggling.js"]

Diagram sources

  • [main.css:3-46](file://src/assets/css/main.css#L3-L46)
  • [main.js:1-14](file://src/assets/js/main.js#L1-L14)

Section sources

  • [main.css:3-46](file://src/assets/css/main.css#L3-L46)
  • [main.js:1-14](file://src/assets/js/main.js#L1-L14)

Performance Considerations

  • CSS custom properties reduce duplication and enable efficient theme switching without reprocessing stylesheets.
  • IntersectionObserver in theme-toggling.js uses a centered viewport threshold to minimize unnecessary recalculations.
  • LocalStorage persistence avoids repeated theme computations on subsequent visits.
  • Media queries are scoped to device-specific concerns to avoid excessive repaints.

Troubleshooting Guide

Common issues and resolutions:

  • Theme toggle not persisting:
    • Verify localStorage availability and that the toggle sets aria-checked correctly.
    • Confirm body classes are applied and CSS selectors target the expected theme states.
  • Theme not updating components:
    • Ensure theme CSS modules are imported after variables and utilities.
    • Check that component selectors rely on body classes rather than hardcoded values.
  • Observer not changing theme classes:
    • Validate data-theme attributes on sections and the observer thresholds/margins.
  • Cursor not adapting to theme:
    • Confirm on-light-bg/on-dark-bg classes are toggled and cursor styles target these classes.

Section sources

  • [material-design-3-main-theme-toggle.js:10-16](file://src/assets/js/modules/material-design-3-main-theme-toggle.js#L10-L16)
  • [iaa-alliance-theme-toggle.js:10-16](file://src/assets/js/modules/iaa-alliance-theme-toggle.js#L10-L16)
  • [theme-toggling.js:9-18](file://src/assets/js/modules/theme-toggling.js#L9-L18)
  • [03-custom-cursor.css:33-36](file://src/assets/css/modules/03-custom-cursor.css#L33-L36)

Conclusion

The design system foundation establishes a robust, token-driven approach to styling with a clear separation of concerns: variables and resets in CSS, global utilities for consistency, MD3-inspired theming with elevation and color roles, and JavaScript-powered theme toggles with persistence. This architecture ensures maintainable, scalable theming and responsive behavior across components and pages.